Why use the debug 2.0 ROM and the PalmOS Emulator?

There are two primary reasons. First, you can use this to verify that
your applications work properly under the 2.0 revision of PalmOS, even
without access to the new hardware. Second, because of the additional
error-checking code in this debug version of the ROM, you can make your
applications more robust and increase the probability that your
application will work properly under future revisions of the OS.

Important: Note that the presence of the extra debug code means that
some applications will fail with the debug ROM, though they have no
visible problems on the production device. Our testing has shown
extremely few cases where an application behaves differently on a Palm
III than on a Palm Pilot. If the debug ROM shows an error, however, it
is much more likely that your application may fail in future revisions
of the OS, since normally the situation is that the software is doing
something incorrect but it doesn't happen to have noticeable
consequences... yet.

If the extra ROM debugging code finds a problem, it will call
ErrFatalDisplayIf() or ErrDisplay(). If there is no debugger connected,
that will result in a "Fatal Error" dialog, reporting the name of the
ROM source file in which the error was detected. If a debugger (such as
Metrowerks CodeWarrior or the Pilot Debugger) is connected, it will show
the location of the error and let you examine the stack to find your
bug.


How to use the debug 2.0 ROM and the PalmOS Emulator

When the files are extracted from the archive, you'll have a ROM file
named "Palm 2.0 Debug.ROM". In order to use this ROM file, you'll need
to download the PalmOS Emulator. Copy the ROM file into the PalmOS
Emulator directory and double-click on the emulator to launch it. You
should see the emulator boot the ROM. When running under Windows, you
can control (and quit) the PalmOS Emulator by right-clicking on the
window to get a popup menu.

The PalmOS Emulator supports an API for external debuggers. At this
time, only Metrowerks' MWDebug debugger (from CodeWarrior) supports this
API in the form of an updated PilotPlugin component. Download this
component and use it to replace the same-named component in your
CodeWarrior installation. You can then start the debugger as normal; it
should behave just as if it was connected to a real Palm Computing
Platform device, even though it's actually working in conjunction with
the emulator. By using the debugger's preferences panels, you can
configure the debugger to target either the PalmOS Emulator or an actual
hardware device when debugging.


Feedback, questions and futures

To give feedback about the PalmOS Emulator, ask questions about it, and
discuss new features and capabilities, please join the PalmOS Emulator
mailing list at http://ls.palm.com.

To ask general questions about the OS or get help debugging your
application, join the Palm Developer Forum, also at http://ls.palm.com.
This forum includes many experienced PalmOS developers, as well as
employees of Palm Computing.

If you have a more confidential programming question, feel free to
contact us at devsupp@palm.com for programming questions.


What is the PalmOS Emulator anyway?

The PalmOS Emulator emulates the hardware of the various models of Palm
Pilot devices. It was originally known as Copilot, and was not written
by Palm Computing, but by several different developers, principally Greg
Hewgill. The software in these archives has been enhanced with new
features, debugging support, and support for the PalmOS 2.0 ROM. For
more information on the changes, read the release notes that come with
the PalmOS Emulator distribution.

For more information about the original Copilot, see  Greg Hewgill's
Copilot web site. http://www.hewgill.com/pilot/copilot/index.html

Palm plans to continue adding more features to the PalmOS Emulator. For
more details, join the mailing list as mentioned above.
